Written by: Jason Hodges-Harris, Developer Technical Support.
Interesting functions and how they operate
Color QuickDraw specific:
There are a few functions within this application which should be of special interest. One of the which is the InvertColorTable() function included below. This is one example of how to safely manipulate a ColorTable , directly altering the values contained within each color entry.
The theDocHndl structure passed into the function contains the handle to the window document structure which is to be edited. This is then accessed to determine the number of entries in the color table and the ColorTable Handle is locked down to avoid it moving in memory as the handle is dereferenced to a pointer for the loop operation to increase performance. After completion of the color amendments the CTabChanged() function is called for the ColorTable to notify that the structure had been altered. Finally the Handle is unlocked as its now safe to move in memory.
The other approach taken to manipulate color information was the use of a custom color search function. The following function implements a brightness control with a full range resolution of 32 steps. It takes the RGBColor value passed into the color search and adds a set value to each color component and limits the maximum color value to 0xFFFF.
To call this function, a code block similar to the following can be used (this example is part of the ImageBrightness() function located in the imageFilter.c file):
Before using the custom color search function a routine descriptor has to be created for it to operate in native Power PC code. The UPP is then added to the GDevice's search list and by calling CopyBits() with both the source and destination ports set to the image port to be amended, alters the port's colors without requiring the allocation of more memory. All that is left is for the color search to be removed from the search list and the routine descriptor disposed as they're no longer required.
The following section of code has been taken from the MirrorImageHorizontal() function and comprises of the loop used to read data from a directly from a locked Gworld PixMap into a pointer based buffer and from one part of the PixMap to another all using BlockMoveData() to avoid cache flushing (which can seriously reduce performance in Power PC code).
The in the example below the temporary storage buffer has been created, the PixMap locked down and the address mode set to 32 bits. The base address of the PixMap is then returned and the width of the PixMap in bytes, the mid Y axis value and the last line value are calculated. Then the loop processes the PixMap data from its original to its new location depending on the image bit depth.
………
basePixMapAddr = imageLinePtr = GetPixBaseAddr(thePixMapHndl); // base addr of image GWorld PixMap
The following code block is used to convert Color QuickDraw commands to their nearest QuickDraw GX equivalents. By calling CopyBits() onto itself the translator function creates a gxBitmap shape containing the converted image data. The second routine below is the shape spooling function required by GXInstallQDTranslator() which is passed the translated objects. Even though the translation is not 100% accurate, as only PixMaps are converted from Color QuickDraw to QuickDraw GX, there is minimal/no difference between the two and therefore this technique is more than suitable.
As the is no function within QuickDraw GX to directly support a mirror image transformation, the following code block taken from the MirrorGxShape() function, shows how such an operation can be created by the manipulation of a gxShape's transformation matrix.
To determine which axis is to be altered, a boolean is passed as a parameter in the function.
First the transformation structure of the gxShape is returned and elements of the matrix are reset to their identity values with the exception of the values stored in location [0][0] and [1][1], as these control the mirror transformation.
By setting the [0][0] to ff(-1) and location [1][1] to ff(1), the image is mirrored along the Y axis and the other valid setting is [0][0] to ff(1) and [1][1] to ff(-1). Note also that setting both of these value to ff(1) produces and identity transformation and both to ff(-1) will negate the pixel locations effectively mirroring the image in the line x = 0. The other setting of ff(0) produces 0 results and therefore is of little normal use. Then set the amended transformation matrix to the gxShape and notify that the gxShape's transformation has altered.
InvalRect(&theWindow->portRect); // invalidate window port rect
SetGWorld(oldPort,theGDevHndl);
…………
General application:
As there can be multiple document windows open and each can either contain Color QuickDraw or QuickDraw GX image data, as well as the status window containing the windows color information, the following code block outlines how the problem of handling the update events was solved.
The code below is the main section of the DoWindowUpdate() function and after starting the update process retrieves the refcon value for the window to be updated. This value contains the handle to the window document structure and by checking values stored in this structure determines what the type of window requiring the update is and therefore calls the correct redraw function.
if (theWindDocHndl && (**theWindDocHndl).isColorsWindow == false &&
(**theWindDocHndl).isUsingQDGX == false)
{
TransferImageToWindow(theWindDocHndl,theWindow); // Color QD content region update
UpdateControls(theWindow,theWindow->visRgn);
DrawGrowIcon(theWindow);
}
else if (theWindDocHndl &&
(**theWindDocHndl).isColorsWindow == false &&
(**theWindDocHndl).isUsingQDGX)
{
UpdateGXObjectDisplay(theWindDocHndl, theWindow);
UpdateControls(theWindow,theWindow->visRgn);
DrawGrowIcon(theWindow);
}
else if ((**theWindDocHndl).isColorsWindow &&
(**theWindDocHndl).isUsingQDGX == false)
DrawImageColors(theWindow);
EndUpdate(theWindow); // end update process
………
Known limitations and bugs:
• In the initial release version there was a nasty intermittent bug when converting a Color QuickDraw based image to
a QuickDraw GX shape. This was tracked down to the spool routine disposing of the gxShape passed into the routine and the gxShape being disposed of a second time from inside the GXInstallQDTranslator() function. As the spool routine was closely based on the listing 1-6 on page 1-22 of Inside Macintosh QuickDraw GX "Environment and Utilities", it appears that this listing is in error and the GXDisposeShape() call in the spool routine should not be used.
• If the application is built with either Think C 7.0.x or the 68k version of CodeWarrior and it is compiled and linked with 2 byte ints, then certain of the effects functions can crash the machine. This is currently being tracked down and will be fixed in a future release. In the short term if the application is built using 4 byte ints, this problem doesn't occur.
• When a QuickTime compressed PICT is loaded, as the depth of the GWorld is reliant on the information returned by GetPictInfo(), this causes only a value of 1 to be returned as GetPictInfo() isn't aware of the new QuickTime image PICT opcodes. The result is that the loaded image is stored as a dithered black and white image. As this problem is known about, a solution has already been planned and is high on the agenda for fixing in the next release.
• The "Show Image Colors" window doesn't update correctly when the active image windows are switched and they contain images of different bit depths.
• The correct "Model", either QuickDraw GX or Color QuickDraw, must be selected before saving an image. If the incorrect model is in use, the image will not be saved.
Further enhancements and improvements.
I hope that this application has provided some useful information regarding the parsing of foreign image file formats, the manual creation of color tables, writing directly into a GWorld, QuickDraw GX transform manipulations and how its possible to integrate both Color QuickDraw and QuickDraw GX into a single application. Also if you're thinking about QuickDraw GX, it should provide a starting point for your own experiments and i've also listed below a few pointers where improvements and enhancements could be made and are currently under consideration for future versions..
• Support for active scrolling of the contents of the image windows, including updating the window contents when dragging a scroll bar thumb control. This has been left out of the current release as certain GX based operations can be slow to redraw. Therefore, redrawing take place only after the mouse button has been released.
• Support for drag and drop between windows including the conversion between both imaging technologies (this could be only one way) and the ability to drag the image to the window to create new file via HFSflavor drag operation.
• Greater support for the TIFF file format including compression and the ability to save the file in this format with both compression (optional) and in either PC or Mac byte order.
• Altering the architecture of the application so that the filters and processing effects are based on components and during the initialization phase the application determines what functionality is available.
• Full support for loading QuickDraw GX based image files. This is of high importance although time beat this feature being included in this release, expect to see its inclusion soon.
• Menu handling to be improved so that only those items which are can be selected are enabled for use. e.g. if a menu item performs a different function dependent on the imaging model used or the current windows state, then this should be reflected in the state of the menu item.
• Support for a method of conversion between QuickDraw GX to Color QuickDraw. Even though there is now the QuickTime codec which supports such a facility, it would be useful for example to convert directly between a gxBitmap Shape object to a PixMap including color information.
